home *** CD-ROM | disk | FTP | other *** search
/ Macademic for Students & Teachers / Macademic for Students and Teachers (Quantum Leap)(1992).iso / Fun & Games / Wator / Wator.doc next >
Encoding:
Text File  |  1985-03-20  |  8.5 KB  |  611 lines  |  [TEXT/MACA]
  1.  
  2.  
  3.                         Wator Documentation
  4.  
  5.  
  6.     
  7.     
  8.     
  9.           
  10. ---------------------
  11.  
  12.  
  13.     
  14.     
  15.     
  16.            
  17.  
  18. The program of Wator has been provided as an example of MACINTOSH
  19.  
  20. programming.  The development environment was AZTEC C, on a 128K MAC
  21. with
  22.  
  23. an external drive.  If you find this example valuable, I would appreciate a
  24.  
  25. nominal contribution of $5 so that I can continue to provide programming
  26.  
  27. examples of this kind.
  28.  
  29.  
  30.  
  31.  
  32.         Send to:
  33.  
  34.  
  35.     
  36.     
  37.         Robert Martin
  38.  
  39.  
  40.     
  41.     
  42.         2826 Lee Ave
  43.  
  44.  
  45.     
  46.     
  47.         Waukegan, IL
  48.  
  49.  
  50.     
  51.     
  52.     
  53.     
  54.         60085
  55.  
  56.  
  57.  
  58. Comments can be sent via EMAIL to 70156,240
  59.  
  60.  
  61.  
  62.  
  63.  
  64.                             Wator
  65.  
  66.                            -------
  67.  
  68.  
  69.  
  70. The game of WATOR was invented by A. K. Dewdney.  He wrote about it in 
  71.  
  72. the "COMPUTER RECREATIONS" column of the DEC '84 issue of "SCIENTIFIC
  73.  
  74. AMERICAN".  The world of wator is a toroidal planet, completely covered
  75.  
  76. with water.  For the purpose of this program, the surface of the torus has
  77.  
  78. been unfolded, and is displayed as a rectangle.
  79.  
  80.  
  81.  
  82. Wator has two types of inhabitants: sharks and fish.  The fish have an 
  83.  
  84. unlimited food supply, breed happily.  The sharks eat only fish, and will
  85.  
  86. starve without food.  Sharks also breed.
  87.  
  88.  
  89.  
  90. Time passes on wator in increments called chronons.  Each chronon, the
  91. fish
  92.  
  93. and sharks move, eat, and breed.
  94.  
  95.  
  96.  
  97. To start the game going, the user must decide on 5 critical values.
  98.  
  99.     
  100.  
  101.     % The initial
  102. number of fish
  103.  
  104.     % The initial
  105. number of sharks
  106.  
  107.     % The number of
  108. chronons it takes for a fish to breed.
  109.  
  110.     % The number of
  111. chronons it takes for a shark to breed.
  112.  
  113.     % The number of
  114. chronons it takes for a shark to starve.
  115.  
  116.  
  117.  
  118. Once these values are set, there is nothing to do but watch as the sharks
  119.  
  120. and fish arrange themselves into a neat little ecology.  Sometimes the
  121.  
  122. system becomes unstable, and all the fish get eaten.  Of course then all
  123.  
  124. the sharks die.  Sometimes, there are too few fish to support all the
  125. sharks
  126.  
  127. and the sharks all die, but the fish survive.  Only the fish can win this
  128.  
  129. game.  The best the sharks can do is draw.
  130.  
  131.  
  132.  
  133. Each fish and shark move in a random fashion, one space per chronon.  If
  134.  
  135. a shark can eat a fish in an adjacent space, it will do that rather than
  136.  
  137. move to an empty square.  The fish do not try to evade the sharks.  When
  138.  
  139. it comes time for a fish or a shark to breed, it must first move to an
  140. empty
  141.  
  142. space, and then it leaves a fully mature offspring behind in the space it
  143.  
  144. came from.
  145.  
  146.  
  147.  
  148.                       Running the program
  149.  
  150.                      ---------------------
  151.  
  152.  
  153.  
  154. To start the game, double click the shark-and-fish icon of "wator".  The 
  155.  
  156. opening sequence will run, and then a dialog box will be presented with
  157.  
  158. the 5 values that you must specify.  The default values represent a stable
  159.  
  160. situation which is my favorite.  Edit the values with mouse and keyboard,
  161.  
  162. and push the "OK" button.
  163.  
  164.  
  165.  
  166. The screen will fill with 3 windows.  The most prominent, labelled "wator"
  167.  
  168. is the rectangular representation of the unfolded torus of the planet of
  169.  
  170. "Wator".  In this window you will see black squares which are the sharks,
  171.  
  172. and smaller grey squares which are the fish.  As you watch they will dance
  173.  
  174. around and multiply.  The sharks will gobble down fish and array
  175. themsevles
  176.  
  177. in fierce competition for feeding space.
  178.  
  179.  
  180.  
  181. The second most prominent window is the population graph.  This window
  182.  
  183. displays two traces, the grey trace represents the fish population,
  184.  
  185. the black trace represents the shark population.  Each vertical division on
  186.  
  187. the graph represents 200 individuals.  Each horizontal division represents
  188.  
  189. 50 chronons.  A vertical separator bar divides the graph.  To the left are
  190.  
  191. the latest recordings, and to the right are the oldest.  The separator moves
  192.  
  193. from left to right, and then starts over again at the far left.
  194.  
  195.  
  196.  
  197. The last window is labeled "statistics".  It contains the current count of
  198.  
  199. sharks and fish.  It also contains the current time in chronons.
  200.  
  201.  
  202.  
  203. Each of these windows may be dragged around with the mouse.
  204.  
  205.  
  206.  
  207. To stop the game, select "Quit" from the "Wator" menu.
  208.  
  209.  
  210.  
  211. Wator screens may be printed with the "caps-lock,shift,command-4"
  212. sequence.
  213.  
  214. (see macintosh manual page 73).
  215.  
  216.  
  217.  
  218.  
  219.  
  220.                              Wator Software
  221.  
  222.                             ----------------
  223.  
  224.  
  225.  
  226. Wator was written in C, using the AZTEC C compiler.  I began writing it
  227.  
  228. before I had recieved my copy of "INSIDE MACINTOSH", and so alot of the
  229.  
  230. initial work was based on educated guessing.  The initial version of Wator
  231.  
  232. drew a rectangle on the screen, and manipulated the sharks and fish within
  233.  
  234. it.  The initial values were retrieved as command line parameters.  Later I
  235.  
  236. added the statistics rectangle, and still later I changed the two rectangles
  237.  
  238. into windows.
  239.  
  240.  
  241.  
  242. After I recieved "INSIDE MACINTOSH" I was able to add the opening
  243. sequence
  244.  
  245. (which uses a method which is based on the "About File..." portion of
  246.  
  247. the wonderful example program written by Cary Clark), the dialog box
  248.  
  249. for parameters, the population graph and the event handling.
  250.  
  251.  
  252.  
  253. Wator consists of 9 source files:
  254.  
  255.  
  256.  
  257.     % Wator.
  258. c    The root module,
  259. contains the rules for operating the
  260.  
  261.  
  262.     
  263.     
  264.         sharks and fish. 
  265. Also contains the highest level code
  266.  
  267.  
  268.     
  269.     
  270.         for controlling the
  271. ancillary functions such as event
  272.  
  273.  
  274.     
  275.     
  276.         dectection, and
  277. window updates.
  278.  
  279.     
  280.  
  281.     % Watorut.
  282. c    Wator Utilities.  A
  283. set of utilities used almost
  284.  
  285.  
  286.     
  287.     
  288.         exclusively by
  289. wator.c in order to draw the sharks and
  290.  
  291.  
  292.     
  293.     
  294.         fish, and control
  295. some of the mathematical limitations
  296.  
  297.  
  298.     
  299.     
  300.         of the torus.
  301.  
  302.  
  303.     
  304.     
  305.         
  306.  
  307.     % Watevent.
  308. c    Detects and
  309. handles mouseDown, keyDown, and Update
  310.  
  311.                     events. 
  312. Knows how to drag windows.
  313.  
  314.  
  315.     
  316.     
  317.     
  318.         
  319.  
  320.     % Watopen.
  321. c    Contains the
  322. opening sequence.  The animation in this
  323.  
  324.                 program is
  325. quite intriguing, and a close examination
  326.  
  327.  
  328.     
  329.     
  330.         should be a
  331. rewarding experience.
  332.  
  333.  
  334.     
  335.     
  336.         
  337.  
  338.     % Watparm.
  339. c    Puts up the dialog
  340. box to get the initial values.  This
  341.  
  342.  
  343.     
  344.     
  345.         module is most
  346. interesting for finding out how to put
  347.  
  348.  
  349.     
  350.     
  351.         Icons into dialog
  352. boxes.
  353.  
  354.  
  355.     
  356.     
  357.         
  358.  
  359.     % Watgraph.
  360. c    Draws and
  361. maintains the population graph.  This was
  362.  
  363.  
  364.     
  365.     
  366.     
  367.         probably the most
  368. chalenging module to write.  There
  369.  
  370.  
  371.     
  372.     
  373.     
  374.         are several
  375. subtleties whithin Quickdraw which I found
  376.  
  377.  
  378.     
  379.     
  380.     
  381.         out about.  This
  382. module is also about as large as
  383.  
  384.  
  385.     
  386.     
  387.     
  388.         the AZTEC C will
  389. support on a 128K MAC.  As it is I
  390.  
  391.  
  392.     
  393.     
  394.     
  395.         had to compile it
  396. using {-Z200} to reduce the string
  397.  
  398.  
  399.     
  400.     
  401.     
  402.         space.  A close
  403. examination of this routine will be
  404.  
  405.  
  406.     
  407.     
  408.     
  409.         very rewarding.  It
  410. covers some animation techniques
  411.  
  412.  
  413.     
  414.     
  415.     
  416.         as well as
  417. techniques for drawing graphs, and updating
  418.  
  419.  
  420.     
  421.     
  422.     
  423.         windows.
  424.  
  425.     
  426.  
  427.     % Watmenu.
  428. c    Controlls the menu
  429. bar, and the execution of menu commands.
  430.  
  431.     
  432.  
  433.     % Wator.
  434. h    Contains all the
  435. global constants and data structures.
  436.  
  437.     
  438.  
  439.     % std.
  440. h
  441.         My own standard
  442. header, which has my favorite conventions
  443.  
  444.  
  445.     
  446.     
  447.         installed.
  448.  
  449.     
  450.  
  451.     
  452.  
  453.                            
  454. Wator Resources
  455.  
  456.  
  457.     
  458.     
  459.     
  460.     
  461.           
  462. -----------------
  463.  
  464.  
  465.  
  466. I built all the resources with the first release of Apples Resource Editor
  467.  
  468. which comes with the software supplement, and is also available from the
  469.  
  470. MAUG.  I kept the resources in a file named wator.res, and merged them
  471. into
  472.  
  473. my linked code before running.  I have not provided a copy of wator.res, 
  474.  
  475. since all the resources are available in the application itself.  If you
  476.  
  477. wish to do any development work on this program, I suggest that you first
  478.  
  479. strip out the resources and then merge them back in when your changes
  480. have
  481.  
  482. been made.
  483.  
  484.  
  485.  
  486.  
  487.     
  488.     
  489.     
  490.     
  491.     
  492.         Linking Wator
  493.  
  494.  
  495.     
  496.     
  497.     
  498.     
  499.            ---------------
  500.  
  501.  
  502.     
  503.     
  504.     
  505.         
  506.  
  507. I have provided a file named wator.lnk which contains the linking 
  508.  
  509. instructions for the linker.  The command used to link the code after is
  510.  
  511. is all compiled is:    ln -f wator.lnk
  512.  
  513.  
  514.  
  515.                             File Type
  516.  
  517.  
  518.     
  519.     
  520.     
  521.     
  522.            -----------
  523.  
  524.  
  525.     
  526.     
  527.     
  528.     
  529.            
  530.  
  531. The Application is given the type type of:   APPL WATX  by the "Set File"
  532.  
  533. utility that comes with the software supplement.  The bundle bit is set
  534.  
  535. at the same time.  
  536.  
  537.  
  538.  
  539.                             License
  540.  
  541.  
  542.     
  543.     
  544.     
  545.     
  546.            ---------
  547.  
  548.  
  549.     
  550.     
  551.     
  552.     
  553.            
  554.  
  555. This program may be used by anyone. I don't care if you copy it a million
  556.  
  557. times, or give it away to all your freinds and relatives.  But please don't
  558.  
  559. charge any money for it.  Also, if you copy the source code, please copy
  560.  
  561. this document with it.  
  562.  
  563.  
  564.  
  565.                             What about me?
  566.  
  567.  
  568.     
  569.     
  570.     
  571.     
  572.           
  573. ----------------
  574.  
  575.  
  576.     
  577.     
  578.     
  579.     
  580.            
  581.  
  582. The game itself is yours.  But if this write-up and the associated source
  583.  
  584. code teach you something worth while, then I would appreciate a 
  585.  
  586. contribution of $5 to help me keep providing educational material like this.
  587.  
  588.  
  589.  
  590.     Send to
  591. :    Robert Martin
  592.  
  593.  
  594.     
  595.     
  596.         2826 Lee Ave
  597.  
  598.  
  599.     
  600.     
  601.         Waukegan, IL
  602.  
  603.  
  604.     
  605.     
  606.     
  607.         60085
  608.  
  609.  
  610.  
  611.